home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1992 June: ROMin Holiday / ADC Developer CD (1992-06) (''ROMin Holiday'')_iso / Developer Connection - 06-1992.iso / Development Platforms / Apple II / Essentials / Technical.Notes / IIGS / TN.IIGS.086 < prev    next >
Encoding:
Text File  |  1991-06-28  |  8.2 KB  |  182 lines  |  [TEXT/pdos]
  1. Apple II
  2. Technical Notes
  3. _____________________________________________________________________________
  4.                                                   Developer Technical Support
  5.  
  6.  
  7. Apple IIgs
  8. #86:         Risking Resourceful Code
  9.  
  10. Revised by:  Matt Deatherage                                       March 1991
  11. Written by:  C.K. Haun <TR>                                    September 1990
  12.  
  13. This Technical Note covers considerations you need to keep in mind when using
  14. code resources.
  15.  
  16. Changes since September 1990:  Now lists XCMD and XFCN resources as "Apple's
  17. code" and notes that other restrictions apply to them as well.
  18. _____________________________________________________________________________
  19.  
  20.  
  21. Code resources are wonderful things that can make your life better than it 
  22. ever was before.  Code resources are necessary when writing CDevs and can be 
  23. very useful for control definition procedures, code modules for extensible 
  24. programs like resource editors in fact, almost anywhere where you use regular 
  25. compiled and linked code.  But to do it right, you need to keep some rules in 
  26. mind.
  27.  
  28.  
  29. Apple's Code, Apple's Rules
  30.  
  31. The first code resources covered are the ones defined as fully supported by 
  32. the System Software.  These are rCtlDefProc ($800C), rCodeResource ($8017), 
  33. rCDEVCode ($8018), rXCMD ($801E) and rXFCN ($801F).  Before looking at the 
  34. specifics, this Note describes in general terms what happens when the 
  35. Resource Manager loads a code resource.
  36.  
  37. When you call the Resource Manager with a request for a code resource (or 
  38. when the system does, as with rCtlDefProcs ), it loads it like a normal 
  39. resource. The Resource Manager finds the resource in a resource map in the 
  40. current search path, allocates a handle for the resource using the attributes 
  41. in the resource attribute bits, and loads the resource into memory.
  42.  
  43. Now the Resource Manager examines the resConverter bit in the resource 
  44. header. If this bit is set, indicating that this resource needs to be 
  45. converted (asit should be for an rCtlDefProc), the Resource Manager checks 
  46. its tables to seeif a resource converter has been logged in (with the 
  47. ResourceConverter call).For code resources, the correct converter has been 
  48. logged in by the manager associated with that resource type.  For example, 
  49. the Control Manager logs in the code resource converter for rCtlDefProc 
  50. resource type.
  51.  
  52. For code resources,  InitialLoad2 is used to load the OMF from memory.  Then 
  53. the Resource Manager returns a handle containing a pointer to the start ofthe 
  54. loaded, relocated code.
  55.  
  56. Rule 1: Code resources must be smaller than 64K
  57.  
  58. The code resource converter uses the InitialLoad2 function of the System 
  59. Loader to load and convert code resources.  That means that code resources 
  60. are restricted in the same way that loading from memory is. One of these 
  61. restrictions is that the code must be 64K or less.
  62.  
  63.  
  64. Rule 2: Compiled and linked code only
  65.  
  66. Again, since InitialLoad2 is used to convert the code resource, the data must 
  67. be in OMF format since  InitialLoad2 expects to relocate standard load 
  68. segments.  When you prepare your code for inclusion in a code resource, 
  69. compile and link the code as you normally would for a stand-alone program.  
  70. Use the file produced by the linker for inclusion in your resource fork.  You 
  71. can use Rez to move the code from a data fork to your application's resource 
  72. fork with a line in your resource description file similar to the following:
  73.  
  74. read rCodeResource (MyCodeIDNumber,locked,convert)"MyCompiledAndLinkedCode";
  75.  
  76. Rule 3: One segment please
  77.  
  78. Multiple segments are theoretically possible with code resources, but you 
  79. have to manage memory IDs and the memory that the additional code segments 
  80. use yourself.  Since the code resource converter calls InitialLoad2, it uses 
  81. the Memory Manager ID for the current resource application, and you cannot 
  82. specify a different user ID directly.  By changing your current resource 
  83. application ID (by making an additional call to ResourceStartUp with a 
  84. modified master ID,for example) you could manage multisegment code resources.
  85.  
  86. Rule 4: No dynamic segments
  87.  
  88. The dynamic segment mechanism does not work with code resources.  Of course, 
  89. your application can still use dynamic segments, but not code resource 
  90. dynamic segments.
  91.  
  92. Rule 5: Set the right attributes
  93.  
  94. There are two sets of attributes you need to be concerned about for a code 
  95. resource.  The first set includes the standard resource attributes; the 
  96. second set covers the attributes that the code itself has in the OMF image.
  97.  
  98. You need both sets to get the functionality you want.  The resource 
  99. attributes determine how the Resource Manager handles the resource.  The OMF 
  100. attributes control what InitialLoad2 does when it converts your code from OMF 
  101. in a resource handle to relocated executable code.
  102.  
  103. Remember, you need to set both sets of attributes.
  104.  
  105. The resource attributes you need to set are locked and convert.  The locked 
  106. flag is necessary to prevent the resource from moving while InitialLoad2 
  107. processes it, and the convert flag is needed to signal the Resource Manager 
  108. to call the code resource converter.
  109.  
  110. You must set the static OMF attribute, the others (like no special memory) 
  111. you set as appropriate for your code in your application.
  112.  
  113. Rule 6: Know where to go
  114.  
  115. The handle you get back from the Resource Manager when you load and convert a 
  116. code resource points to the beginning of the relocated and ready-to-execute 
  117. code, not to the image of the code that is stored in the resource fork.  So 
  118. you can immediately jump to this code to execute it.
  119.  
  120. You can override this if you like clear the resConverter bit in the resource 
  121. attributes.  If this bit is zero, the Resource Manager does not call any 
  122. resource converter (including the code resource converter).
  123.  
  124. Rule 7: Remember the Write
  125.  
  126. Keep in mind that any resource that uses a converter uses that converter both 
  127. for reading and writing the resource.  If you write out a code resource, the 
  128. Resource Manager calls the Write routine for the code resource converter, 
  129. which currently writes without doing any conversion it does not reconvert the 
  130. codein memory back to OMF format.    However, some converters (perhaps one 
  131. you write) could reconvert the resource before writing it out.
  132.  
  133.  
  134. Your Code, Your Rules
  135.  
  136. If you want to define your own code resource type (with a resource type of 
  137. less than $8000 and greater than 0) you may want to follow the same rules as 
  138. the system code resources use.  In fact, you can even use the same code 
  139. resource converter, by using the ResourceConverter call with your resource 
  140. type, andlog the code resource converter as the converter to use with your 
  141. resource type, like the following:
  142.  
  143.        pha
  144.        pha                     ; return space
  145.        _GetCodeResConverter    ; Misc Tools call to return the loader 
  146. *                              ; relocation code pointer
  147. *                              ; (leave it on the stack for the next call)
  148.        pea $0678               ; resource type you want to convert with this 
  149. *                              ; converter, any Application type you wish
  150.        pea %01                 ; add this converter to the Application
  151. *                              ; converter list, and log this routine in
  152.        _ResourceConverter
  153.  
  154. or you can do whatever you like with the resource, including not having a
  155. converter and doing all the relocation and memory management of the code
  156. yourself.  This can give you the ability to add more functionality than the
  157. standard code resources provide dynamic segmentation is one feature you could
  158. implement if you want to handle all the details yourself.
  159.  
  160. Or, you can manage the code any way you want, but keep the built-in system
  161. functions in mind, and use as many of them as you can.  Make your life 
  162. simpler.
  163.  
  164.  
  165. One Final Note
  166.  
  167. If one of your resources is marked convert and preload the Resource Manager
  168. only preloads that resource if the converter for that resource is logged in 
  169. as a converter for that type.  If the Resource Manager cannot find the 
  170. converter, it does not preload the resource.
  171.  
  172.  
  173. Further Reference
  174. _____________________________________________________________________________
  175.   o  Apple IIgs Toolbox Reference, Volume 3
  176.   o  GS/OS Reference
  177.   o  HyperCard IIgs Script Language Guide
  178.   o  HyperCard IIgs Technical Note #1, Corrections to the Script Language 
  179.      Guide
  180.   o  Apple IIgs Sample Code #9, Lister
  181.  
  182.